---
title: Convert a number to English words
summary: Converts a whole number into space-delimited English words.
status: draft
owner: SAIF Documentation Generator
last_reviewed: 2026-08-21
library: SAIF.Business.Utilities
reference_type: embedded
operation_id: op-03-number-to-text
trigger: Caller needs a written-word rendering of a whole number
---

# Convert a number to English words

Recursively converts a whole number to its English-word rendering, decomposing by magnitude band.

| Field | Value |
| --- | --- |
| **Operation ID** | op-03-number-to-text |
| **Trigger** | A caller needs a written-word rendering of a whole number |
| **Inputs** | `n As Long` |
| **Outputs** | Space-delimited English words (trailing space is produced by the unit branch) |
| **Primary components** | `mdlTextConversion.NumberToText` |
| **Entry point** | SAIF.Business.Utilities/mdlTextConversion.vb |

## Steps

1. If `n > 999999999999999`, throw `ApplicationException("Number too large to convert to text.  Limit is 999,999,999,999,999.")` ([BR-013](../business-rules.md#br-013-number-magnitude-limit)).
2. If `n < 0`, return `"Minus "` concatenated with the recursive conversion of `-n` ([BR-014](../business-rules.md#br-014-negative-number-rendering)).
3. If `n = 0`, return an empty string ([BR-015](../business-rules.md#br-015-zero-empty-string)) — this is also the recursion terminator for exact multiples.
4. If `n <= 19`, index the literal ones/teens word array and append a trailing space.
5. If `n <= 99`, index the tens word array via `RoundDown(n, 10) - 2` and recurse on `n Mod 10`.
6. For each higher magnitude band (hundred, thousand, million, billion, trillion) the function emits `"One <band> "` for the `1xxx…` special case, otherwise recurses on `RoundDown(n, band)`, appends the band name, and recurses on `n Mod band` ([BR-016](../business-rules.md#br-016-magnitude-band-decomposition)).

## Process flow

The following diagram visualizes this operation's control flow.

```mermaid
flowchart TD
	Start([Caller invokes NumberToText]) --> CheckLimit{n > 999999999999999?}
	CheckLimit -->|Yes| ThrowEx(["Throw ApplicationException:<br>Number too large to convert"])
	CheckLimit -->|No| CheckNeg{n < 0?}
	CheckNeg -->|Yes| Negate["Return 'Minus ' concatenated<br>with recursive conversion of -n"]
	CheckNeg -->|No| CheckZero{n = 0?}
	CheckZero -->|Yes| ReturnEmpty([Return empty string])
	CheckZero -->|No| CheckTeens{n <= 19?}
	CheckTeens -->|Yes| IndexOnes["Index ones/teens word array,<br>append trailing space"]
	CheckTeens -->|No| CheckTens{n <= 99?}
	CheckTens -->|Yes| TensBranch["Index tens word array via<br>RoundDown(n, 10) - 2,<br>recurse on n Mod 10"]
	CheckTens -->|No| BandCheck{"n is in a higher<br>magnitude band?"}
	BandCheck -->|"1xxx… special case"| OneBand["Emit 'One band '"]
	BandCheck -->|Otherwise| RecurseBand["Recurse on RoundDown(n, band),<br>append band name,<br>recurse on n Mod band"]
	Negate --> Done([Return word rendering])
	IndexOnes --> Done
	TensBranch --> Done
	OneBand --> Done
	RecurseBand --> Done
	ReturnEmpty --> Done
```

## Failure and edge-case behavior
- Only the explicit `ApplicationException` above; no other validation.

## Related documentation
- [Operations and processes](../operations-processes.md)
- [Business rules](../business-rules.md)

## Sources
- `SAIF.Business.Utilities/mdlTextConversion.vb`